fix(ext-agents): select a compatible Python for `azd ai agent run` instead of first on PATH by glharper · Pull Request #9012 · Azure/azure-dev

glharper · 2026-07-07T18:43:04Z

Summary

On Windows, azd ai agent run fails with Python 3.13+ is required (found 3.11.9) even when Python 3.13 is installed and selectable via the Windows Python launcher (py -0 reports 3.13 *). The project declares runtime: python_3_13 in azure.yaml.

Root cause: the pip fallback path resolves Python via findSystemPython, which returned the first of python3 / python / py found on PATH and then hard-failed in checkPythonVersion if that interpreter was too old. When Python311 precedes Python313 on PATH, python.exe is 3.11 and the resolver never falls through to the py launcher that would locate 3.13.

Fix

findSystemPython now probes multiple candidates and checks each one's version, returning the first that satisfies the minimum supported runtime (>= 3.13):

On Windows it prefers the py -3 launcher, which selects the newest installed Python 3 (rather than whichever python.exe is first on PATH), then falls back to python3, python, and the default py.
An interpreter is modeled as an executable path plus leading launcher args (pythonInterpreter{path, args}), so a py -3 selection is carried through to venv creation (py -3 -m venv ...).
When every resolvable candidate is too old, the error names the newest version found so the user knows what is installed.

This makes the pip path behave like the uv path, which already resolves a compatible interpreter via uv venv --python ">=3.13".

# before (Python311 before Python313 on PATH): fails
Python 3.13+ is required (found 3.11.9)

# after: `py -3` locates 3.13 and the venv is created successfully

Changes

internal/cmd/run.go — replace findSystemPython/checkPythonVersion with a version-aware resolver: pythonInterpreter (+command), pythonCandidates, pythonVersion, pythonVersionOK, firstCompatiblePython, and a rewired findSystemPython. Minimum runtime is now the named minPythonMajor/minPythonMinor constants. The pip-path call site uses the resolved interpreter directly.
internal/cmd/run_test.go — unit tests for the selection logic (firstCompatiblePython with an injected version function, covering the Windows repro, skip-too-old, newest-incompatible error, unparseable-version skip, and empty cases), pythonVersionOK, pythonVersion, and the no-Python error.
CHANGELOG.md — Unreleased entry.

Testing

go build ./..., go vet, golangci-lint run ./internal/cmd/ — clean
go test ./internal/cmd/ -count=1 — pass
gofmt and cspell on changed files — clean

Fixes #8954

…first on PATH azd ai agent run's pip fallback resolved Python via findSystemPython, which returned the first of python3/python/py on PATH and then hard-failed in checkPythonVersion if that interpreter was too old. On Windows, python.exe is frequently an older version (e.g. 3.11) even when a newer Python (3.13) is installed and selectable via the 'py -3' launcher, so 'azd ai agent run' failed with 'Python 3.13+ is required (found 3.11.9)'. findSystemPython now probes multiple candidates -- preferring the Windows 'py -3' launcher, which selects the newest installed Python 3 -- and checks each one's version, returning the first that satisfies the minimum runtime (>= 3.13). When every candidate is too old, the error names the newest version found. The interpreter is modeled as an executable plus launcher args so a 'py -3' selection is carried through to venv creation. Fixes #8954 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-07-07T18:43:38Z

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Thank you for logging this issue; our team is reviewing it. If you need urgent prioritization, tag @RickWinter and @kristenwomack to let us know.

Copilot

Pull request overview

This PR fixes azd ai agent run on Windows when multiple Python installations exist by selecting a Python interpreter that satisfies the agent runtime requirement (>= 3.13) instead of using the first python found on PATH, aligning the pip fallback behavior with the existing uv path.

Changes:

Replace the pip-path Python resolver with a version-aware probe that tries multiple candidates (preferring py -3 on Windows) and selects the first compatible interpreter.
Add unit tests covering interpreter selection behavior, version parsing, and error cases.
Add an Unreleased changelog entry for the fix.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
`cli/azd/extensions/azure.ai.agents/internal/cmd/run.go`	Implements a version-aware Python interpreter resolver and uses it for venv creation in the `pip` fallback path.
`cli/azd/extensions/azure.ai.agents/internal/cmd/run_test.go`	Adds tests for version parsing and interpreter selection logic, including the Windows repro scenario.
`cli/azd/extensions/azure.ai.agents/CHANGELOG.md`	Documents the bug fix in the extension’s Unreleased notes.

jongio

Version-aware interpreter resolution with DI for testability, correct Windows launcher ordering, and informative error messages. The slices.Clone in command() prevents arg slice mutation. Looks correct.

RickWinter

This replaces first-python-on-PATH resolution with a version-aware resolver. findSystemPython now probes an ordered candidate set (on Windows the py -3 launcher first, which selects the newest installed Python 3) and returns the first that satisfies >= 3.13, modeling an interpreter as path plus launcher args so a py -3 selection carries through to venv creation. This is the right shape and makes the pip path behave like the uv path's --python ">=3.13" constraint.

The selection logic is factored behind an injected version function and covered directly: the Windows repro (py -3 picks 3.13 over a 3.11 python), skip-too-old, the newest-incompatible error naming the version found, unparseable-version skip, and the empty case. The too-old error now names the newest version on the machine, which is a real usability improvement over the prior hard-fail on whichever python came first.

No correctness or security concerns. Build, vet, lint, and the internal/cmd tests pass.

Disposition: no blockers.

…onstants The uv path hardcoded --python ">=3.13" while the pip path used the minPythonMajor/minPythonMinor constants, so the two could drift out of sync. Add minPythonUvSpec(), which builds the uv specifier from the constants, use it in the uv venv command, and add a test asserting it tracks the constants. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

glharper · 2026-07-08T13:36:02Z

Good call -- addressed in ff179a5. Added minPythonUvSpec(), which builds the uv --python specifier from the shared minPythonMajor/minPythonMinor constants, and switched the uv venv command to use it. The pip-path version checks already use those constants, so both paths are now driven by a single source of truth. Also added TestMinPythonUvSpec asserting the specifier tracks the constants, so bumping the minimum stays in sync automatically.

glharper requested a review from JeffreyCA as a code owner July 7, 2026 18:43

Copilot AI review requested due to automatic review settings July 7, 2026 18:43

glharper requested review from huimiu, hund030, therealjohn, trangevi and trrwilson as code owners July 7, 2026 18:43

microsoft-github-policy-service Bot assigned glharper Jul 7, 2026

Copilot started reviewing on behalf of glharper July 7, 2026 18:43 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

github-actions Bot added the ext-agents azure.ai.agents extension label Jul 7, 2026

jongio approved these changes Jul 7, 2026

View reviewed changes

RickWinter reviewed Jul 7, 2026

View reviewed changes

trangevi requested changes Jul 7, 2026

View reviewed changes

Comment thread cli/azd/extensions/azure.ai.agents/internal/cmd/run.go

jongio approved these changes Jul 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(ext-agents): select a compatible Python for `azd ai agent run` instead of first on PATH#9012

fix(ext-agents): select a compatible Python for `azd ai agent run` instead of first on PATH#9012
glharper wants to merge 2 commits into
mainfrom
glharper/agent-run-python-runtime-8954

glharper commented Jul 7, 2026

Uh oh!

github-actions Bot commented Jul 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

jongio left a comment

Uh oh!

RickWinter left a comment

Uh oh!

Uh oh!

glharper commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

glharper commented Jul 7, 2026

Summary

Fix

Changes

Testing

Uh oh!

github-actions Bot commented Jul 7, 2026

📋 Prioritization Note

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

RickWinter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

glharper commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants